home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / biblio / bibtex / utils / bibsort / bibsort.hlp < prev    next >
Text File  |  1992-10-18  |  9KB  |  201 lines
  1. 1 DVI
  2.      bibsort - sort a BibTeX bibliography file
  3.  
  4. 2 SYNOPSIS
  5.  SYNOPSIS
  6.      bibsort [optional sort(1) switches] < infile >outfile
  7.  
  8. 2 DESCRIPTION
  9.  DESCRIPTION
  10.      bibsort filters a BibTeX bibliography, or bibliography frag-
  11.      ment,  on    its standard input, printing on    standard output    a
  12.      sorted bibliography.
  13.  
  14.      Sorting is    by BibTeX tag name, or by @String macro    name, and
  15.      letter case is ignored in the sorting.
  16.  
  17.      If    no command-line    switches are provided for  sort(1),  then
  18.      -f     is  supplied to cause letter case to be ignored.  If you
  19.      also want to remove duplicate entries, you    could specify the
  20.      switches -f -u.
  21.  
  22.      The input stream is conceptually divided  into  four  parts,
  23.      any of which may be absent.
  24.  
  25. 2     --1.--Introductory--material--such--as    -comments,---file
  26.        1.  Introductory  material  such  as     comments,   file
  27. 2     ------headers,    and-edit-logs-that-are-ignored-by-BibTeX.
  28.            headers,    and edit logs that are ignored by BibTeX.
  29. 2     ------No-line-in-this-part-begins-with-an-at-sign,-``@''.
  30.            No line in this part begins with an at-sign, ``@''.
  31.  
  32. 2     --2.--Preamble-material    delineated-by-``@Preamble{''--and
  33.        2.  Preamble material    delineated by ``@Preamble{''  and
  34. 2     ------a    -matching-closing-``}'',-intended-to-be    processed
  35.            a     matching closing ``}'', intended to be    processed
  36. 2     ------by-TeX.--Normally,-there-is-only-one-such    entry--in
  37.            by TeX.  Normally, there is only one such    entry  in
  38. 2     ------a    -bibliography-file,-although-BibTeX,-and-bibsort,
  39.            a     bibliography file, although BibTeX, and bibsort,
  40. 2     ------permit-more-than-one.
  41.            permit more than one.
  42.  
  43. 2     --3.--Macro-definitions    of-the-form-``@String{...}''.    A
  44.        3.  Macro definitions    of the form ``@String{...}''.    A
  45. 2     ------single--macro--definition    -may-span-multiple-lines,
  46.            single  macro  definition     may span multiple lines,
  47. 2     ------and-there    are-usually-several-such-definitions.
  48.            and there    are usually several such definitions.
  49.  
  50. 2     --4.--Bibliography--entries--such--as--``@Article{...}'',
  51.        4.  Bibliography  entries  such  as  ``@Article{...}'',
  52. 2     ------``@Book{...}'',--``@Proceedings{...}'',--and-so-on.
  53.            ``@Book{...}'',  ``@Proceedings{...}'',  and so on.
  54. 2     ------For-bibsort,-any-line-that--begins--with    an--``@''
  55.            For bibsort, any line that  begins  with    an  ``@''
  56. 2     ------immediately--followed--by    letters    and-digits-and-an
  57.            immediately  followed  by    letters    and digits and an
  58. 2     ------open-brace-is-considered-to-be-such-an-entry.
  59.            open brace is considered to be such an entry.
  60.  
  61.      The order of these    parts is preserved in the output  stream.
  62.      Part  1  will  be    unchanged,  but    parts 2--4 will    be sorted
  63.      within themselves.
  64.  
  65.      The sort key of ``@Preamble'' entries is their initial line,
  66.      of     ``@String''  entries,    the macro name,    and of all BibTeX
  67.      entries, the citation tag between the open    curly  brace  and
  68.      the trailing comma.
  69.  
  70.      bibsort will correctly handle UNIX    files with LF line termi-
  71.      nators, as    well as    IBM PC DOS files with CR LF line termina-
  72.      tors; the essential requirement is    that input lines be  del-
  73.      ineated by    LF characters.
  74.  
  75. 2 CAVEATS
  76.  CAVEATS
  77.      BibTeX has    loose syntactical requirements that  the  current
  78.      simple  implementation of bibsort does not    support.  In par-
  79.      ticular, outer parentheses    may  not  be  used  in    place  of
  80.      braces  following    ``@keyword''  patterns,     nor may there be
  81.      leading or    embedded whitespace.
  82.  
  83.      If    you have such a    file, you can use bibclean(1) to  pretty-
  84.      print it into a form that bibsort can handle successfully.
  85.  
  86.      The user must be aware that sorting a  bibliography  is  not
  87.      without peril, for    at least these reasons:
  88.  
  89. 2     --1.--BibTeX-has-a-requirement-that-entry-tags    given--in
  90.        1.  BibTeX has a requirement that entry tags    given  in
  91. 2     ------crossref    =--tag-pairs-in    a-bibliography-entry-must
  92.            crossref    =  tag pairs in    a bibliography entry must
  93. 2     ------refer-to-entries-defined-later,--rather--than--ear-
  94.            refer to entries defined later,  rather  than  ear-
  95. 2     ------lier,--in    -the-bibliography-file.    -This-regrettable
  96.            lier,  in     the bibliography file.     This regrettable
  97. 2     ------implementation-limitation    of-the-current    (pre-1.0)
  98.            implementation limitation    of the current    (pre-1.0)
  99. 2     ------BibTeX--prevents-arbitrary-ordering-of-entries-when
  100.            BibTeX  prevents arbitrary ordering of entries when
  101. 2     ------crossref-values-are-present.
  102.            crossref values are present.
  103.  
  104. 2     --2.--If-the-BibTeX-file-contains-interspersed-commentary
  105.        2.  If the BibTeX file contains interspersed commentary
  106. 2     ------between--``@keyword{...}''--entries,--this-material
  107.            between  ``@keyword{...}''  entries,  this material
  108. 2     ------will-be-considered-part-of-the-preceding-entry,-and
  109.            will be considered part of the preceding entry, and
  110. 2     ------will-be-sorted-with-it.--Leading-commentary-is-more
  111.            will be sorted with it.  Leading commentary is more
  112. 2     ------common,-and-will-be-moved    elsewhere-in-the-file.
  113.            common, and will be moved    elsewhere in the file.
  114.  
  115. 2     ------This-is-normally-not--a--problem    for--the--part    1
  116.            This is normally not  a  problem    for  the  part    1
  117. 2     ------material-before-the-``@Preamble'',-since-it-is-kept
  118.            material before the ``@Preamble'', since it is kept
  119. 2     ------together-at-the-beginning    of-the-output-stream.
  120.            together at the beginning    of the output stream.
  121.  
  122. 2     --3.--Some-kinds-of-bibliography-files-should-be-kept--in
  123.        3.  Some kinds of bibliography files should be kept  in
  124. 2     ------a    -different--order-than-alphabetically-by-tags.    A
  125.            a     different  order than alphabetically by tags.    A
  126. 2     ------good-example-is-a    bibliography-file-with    the--con-
  127.            good example is a    bibliography file with    the  con-
  128. 2     ------tents--of    a-journal,-for-which-publication-order-is
  129.            tents  of    a journal, for which publication order is
  130. 2     ------likely-more-suitable.
  131.            likely more suitable.
  132.  
  133.      While a much more sophisticated  implementation  of  bibsort
  134.      could  deal  with    the  first  point, solving the second one
  135.      requires human intelligence and natural language understand-
  136.      ing that computers    lack.
  137.  
  138.      bibsort uses ASCII    control    characters 001    through     007  for
  139.      temporary    modifications  of  the    input  stream.    If any of
  140.      these are already present in the input, they will be altered
  141.      on     output.  This is unlikely to be a problem, because those
  142.      characters    have neither a printable representation, nor  are
  143.      they  conventionally used to mark line or page boundaries in
  144.      text files.
  145.  
  146. 2 PROGRAMMING-NOTES
  147.  PROGRAMMING NOTES
  148.      Some text editors permit application of an    arbitrary  filter
  149.      command  to a region of text.  For    example, in GNU    emacs(1),
  150.      the   command   C-u    M-x       shell-command-on-region,    or
  151.      equivalently,  C-u     M-|,  can  be    used  to run bibsort on    a
  152.      region of the buffer that is devoid of cross references  and
  153.      other material that cannot    be safely sorted.
  154.  
  155.      Some  implementations  of    BibTeX    editing     support  in  GNU
  156.      emacs(1)  have  a    sort-bibtex-entries command that is func-
  157.      tionally similar to bibsort.  However, the     file  size  that
  158.      can  be  processed    by emacs(1) is limited,    while bibsort can
  159.      be    used on    arbitrarily large  files,  since  it  acts  as    a
  160.      filter,  processing  a  small amount of data at a time.  The
  161.      sort stage    needs the entire data  stream,    but  fortunately,
  162.      the  UNIX sort(1) command is clever enough    to deal    with very
  163.      large inputs.
  164.  
  165.      The current implementation    of bibsort follows the UNIX trad-
  166.      ition  of    combining simple already-available tools.  A six-
  167.      stage pipeline of    egrep(1),  nawk(1),  sort(1),  and  tr(1)
  168.      accomplishes  the    job  in     one  pass with    about 70 lines of
  169.      shell script, 60 lines of which is     a  nawk(1)  program  for
  170.      insertion    of  sort keys.    bibsort    was written and    tested on
  171.      several large bibliographies in a couple of hours.     By  con-
  172.      trast, bibtex(1) is more than 11 000 lines    of code    and docu-
  173.      mentation,    and bibclean(1)    is about 1500 lines long.
  174.  
  175. 2 BUGS
  176.  BUGS
  177.      bibsort may fail on  some    UNIX  systems  if  their  sort(1)
  178.      implementations  cannot  handle very long lines, because for
  179.      sorting purposes, each complete bibliography entry     is  tem-
  180.      porarily  folded  into  a    single    line.  You may be able to
  181.      overcome this problem by adding  a     -znnnnn  switch  to  the
  182.      sort(1)  command (passed via the command line to bibsort) to
  183.      increase the maximum line size to some larger value of nnnnn
  184.      bytes.
  185.  
  186. 2 SEE-ALSO
  187.  SEE ALSO
  188.      bibclean(1),   bibtex(1),     egrep(1),   emacs(1),     nawk(1),
  189.      sort(1), tr(1).
  190.  
  191. 2 AUTHOR
  192.  AUTHOR
  193.      Nelson H. F. Beebe, Ph.D.
  194.      Center for    Scientific Computing
  195.      Department    of Mathematics
  196.      University    of Utah
  197.      Salt Lake City, UT    84112
  198.      Tel: (801)    581-5254
  199.      FAX: (801)    581-4148
  200.      Email: <beebe@math.utah.edu>
  201.